The World of Computer Software/The World of Computer Software.iso/pbclon21.zip/PBCLONE.DOC

Text File | 1993-01-12 | 50KB | 1,084 lines

                     The PBClone Library
                   =---------------------=
                         Version 2.1

    PBCLONE  Copyright (c) 1990-1993  Thomas G. Hanlin III



Use of LIBMAT or LIBWIZ is strongly recommended for creating
the initial PBClone library.  You should be able to get these
utilities from the same place you got this library.

This is PBClone, a library of over 550 assembly language and
BASIC routines for use with Microsoft's BASIC compilers:
Bascom, PDS, QuickBasic and Visual BASIC for DOS.  The PBClone
collection is copyrighted and may be distributed only under the
following conditions:

   All PBClone files must be distributed together as a unit.
   No files may be altered, added, or deleted from this unit.

You use this library at your own risk.  It has been tested by
me on my own computer, but I will not assume any responsibility
for any problems which PBClone may cause you.  If you do run
into a problem, please let me know about it, and I will do my
best to verify and repair it.

It is expected that if you find PBClone useful, you will
register your copy.  You may not use PBClone routines in
programs intended for sale unless you have registered.

Registration gets you the latest version of PBClone, complete
with full source code.  The assembly language code is designed
for MASM 6.0 and may require alteration for other assemblers.

You will need to have a complete set of PBClone .OBJ files for
LibWiz to work.  Create a fresh subdirectory and extract the
BASIC sources from PBC$BAS.ZIP (or .LZH, etc).  Compile them
all.  The following DOS command will do it:

   FOR %x IN (*.BAS) DO BC %x /o;

Now extract the .OBJ files from PBC$MAIN.LIB into the same
directory, using the UnLib utility that comes with LibWiz.
Finally, extract the .OBJ files from PBC$NEAR.LIB as well. This
gives you a complete set of .OBJs for PBClone, allowing LibWiz
to create a custom PBClone library for you.

The VB-DOS compiler always uses far strings.  For it, you must
use the .OBJs from PBC$FAR.LIB instead of PBC$NEAR.LIB.

With PDS, you have a choice between near and far strings.  To
use far strings, use the /FS switch when compiling, and use the
.OBJs from PBC$FAR.LIB instead of PBC$NEAR.LIB.

                     Creating .QLB files



If you like to use the BASIC editor/environment, you will need
to create a .QLB version of the library to complement the .LIB
version.  LIBWIZ can do it for you, or you can do it manually.
This is done using the LINK.EXE utility that came with your
compiler.  The exact parameters differ slightly depending on
which version of the compiler you have.  For QuickBasic, it
looks something like this:

   LINK libname.LIB/Q/SE:1024,libname.QLB,NUL,BQLB45;

The BQLB45 file is for QuickBasic 4.5.  This should be replaced
by BQLB40 or BQLB41 for QuickBasic 4.0 (check your files to see
which you have).  For BASCOM 6.0-7.1, also called Professional
Development System or PDS, use QBXQLB instead of BQLB45.  For
VB-DOS, use VBDOSQLB instead of BQLB45.

Since you'll probably want to do this again in the future when
you get a new version of BasWiz or PBClone, I'd suggest you
create a batch file or alias to do the work for you.  If you
have 4DOS, an alias such as the following will do it:

   ALIAS QLB LINK %%1.LIB/Q/SE:1024,%%1.QLB,NUL,BQLB45;

In this case, you can do the conversion simply by typing:

   QLB libname

                     The TSR File Viewer



Since there are hundreds of routines in PBClone, it isn't
always exactly easy to remember which routine you want or how
to use it.  This is a particular problem when you're in the
middle of writing a program.  So, I've written a TSR file
viewer... it's crude, but it gets the job done.

Just type "FV" to install the TSR.  Alt-V activates it.  "FV
/D" removes it from memory.

     !!! ----== NOTE ==---- !!!
Please check FV with a nonessential application first!  It
appears to work fine in the QuickBasic environment, but it
locks up my favorite editor, so I can't guarantee that it will
behave properly in all circumstances.

First, FV will ask you for the file to view.  This may contain
drive and subdirectory information as well as the file name.
Second, you will be asked for a search string.  If you enter a
search string, viewing will start at the part of the file that
contains that search string.  If you just press enter, viewing
will start at the beginning of the file.  The file will be
presented to you one page at a time.  I suggest viewing
PBCLONE.DOC or PBCLONE.INF.

FV was written in BASIC using Crescent's P.D.Q. library, with
the "simplified" TSR handler (which doesn't seem to have been
entirely debugged).  Then again, TSRs are a tricky matter,
especially with BASIC...

                        General Notes



The initial version of PBClone had only one manual.  However,
since there are so many routines, I've split the manual into a
general documentation file and a reference manual.  You won't
want to print PBCLONE.MAN unless you have a lot of time and
printer paper!  In contrast, this file (PBCLONE.DOC) has been
kept small to allow ready printing.  It contains general notes,
cross-reference listings of the routines, and assorted charts.

Many of the routines in PBClone are similar to routines of the
same name in ADVBAS and/or ProBas.  The key here is "similar"--
they don't necessarily work the same way and may not produce
the same results.  If you intend to convert from ADVBAS or
ProBas to PBClone, read the documentation carefully.

When a PBClone returns a Boolean (on or off) value, it will
always be 0 if off, -1 if on; this is unlike ProBas, which
would often return any non-zero value for an "on" state.
Booleans passed to PBClone may still use any non-zero value to
indicate a "true" or "on" condition, however.

Critical error handling has been incorporated into all disk and
device routines.  You will never have to worry about "R>etry,
A>bort, I>gnore" again, so long as you use PBClone for your
disk and device management.

PBClone file handling is very flexible but may be confusing to
people used to BASIC's strongly-moded files.  PBClone file
handling is most similar to BASIC files opened in BINARY mode.
You may read or write any amount of information at a time.
After each read or write takes place, the file pointer is
updated appropriately, so you can use sequential access
techniques without further effort.  Random access is also
possible, using FSetLoc/FSetOfs/FSetRec to set the file pointer
position.  Those of you who are familiar with C or Pascal file
handling will notice strong similarities in this approach,
which is based on techniques that have long been standard in
the industry.

Many routines are available both as SUBprograms and as
FUNCTIONs.  The former is for compatibility with older programs
which were designed before BASIC was capable of using
FUNCTIONs.  You may use either, of course, although the
FUNCTION version of a routine is often more convenient.

                        General Notes



The PBClone library can be used in conjunction with other
libraries.  If there is a conflict in routine names between the
two libraries, the OBJTOOL utility can be used to rename one or
the other routine.  Due to the large size of PBClone, you will
probably need to select just the routines you need, rather than
combining the entire libraries, in order to avoid overflowing
LINK limitations.  OBJTOOL can help you find out which routines
are in what modules.  The LIB utility can be used to alter
existing libraries, or you can build your own custom libraries
from the ground up, using LibWiz.  See the LIB_BI.DOC and
LIBRARY.TXT files if you are not familiar with libraries.

LibMatic, LibWiz and ObjTool are included on the sampler disk
that comes with the registered version of PBClone.  They should
also be available at your local BBS.

If you have not used ADVBAS, ProBas, or PBClone before, you may
be unfamiliar with the array handling conventions used here.
In almost all array routines, you will see a pair of parameters
(e.g. DSeg% and DOfs%) used to represent an array.  These
values are obtained by the BASIC functions VARSEG and VARPTR:

   DSeg% = VARSEG(Array(1))    ' or whatever the first...
   DOfs% = VARPTR(Array(1))    ' ...desired element may be

This is the way that current versions of QuickBasic and BASCOM
pass arrays, TYPEd values, and fixed-length STRING values to
assembly-language routines.  It tells the routine where in
memory to find the value(s).  Since these values may move
around in memory, it is important to get the VARSEG and VARPTR
just before you call the routine.  Any routine that accepts a
segment and an offset can be used with arrays, TYPEd values,
and fixed-length strings interchangeably.  This allows for
considerable flexibility.

Virtually all of the variables used in PBClone are integers.
In this manual, integers are indicated specifically by use of
the "%" integer postfix.  The use of DEFINT A-Z in your program
will cause your variables to be integers by default, which I
would recommend unless you use floating point heavily.

                        General Notes



Most of the routines in ProBas (and all of the routines in
ADVBAS) did not require a DECLARE if the CALL syntax was used.
This is not true of PBClone, which requires DECLAREs.  There
are numerous advantages to this:

   1) BASIC can more easily detect syntax errors.
   2) You may use CALL or the new simplified syntax.
   3) Many of the routines are smaller and faster due to
      use of the DECLARE option BYVAL.

The DECLAREs are generated in a .BI file by LIBWIZ.  Assuming
you named the library PBC, you can include the DECLAREs in your
program with this statement:

   REM $INCLUDE: 'PBC.BI'

The PBC.BI file must be in the same directory as your program,
or you can put it into a specific directory by setting an
environment variable.  I keep my include files in a directory
called C:\INCLUDE, so I have the following line in my
AUTOEXEC.BAT:

   SET INCLUDE=C:\INCLUDE

As mentioned, there are now two ways of calling any
subprogram.  You can use the CALL keyword or an implicit call.
In the case of the CopyFile routine, for instance, you could
use either of these calls interchangeably:

   CALL CopyFile (FromFile$, ToFile$, ErrCode%)

   CopyFile FromFile$, ToFile$, ErrCode%

The latter technique is more elegant, to my tastes, and is the
one used throughout the PBClone documentation and examples.
You may use whichever method you prefer-- BASIC generates the
same code either way.

How you capitalize the names of the variables and routines is
up to you.  I like mixed uppercase and lowercase, but it really
doesn't matter.  You can also change the names of the variables
or even replace them with constants, as long as you maintain
the correct type:

   COPYfile "C:\AUTOEXEC.BAT", "A:AUTOEXEC.BAT", errornumber%

                        General Notes



If you have registered PBClone and wish to reassemble all of the
routines written in assembly language, first place these
routines in their own subdirectory.  Then:

   FOR %x IN (*.ASM) DO MASM %x ;

Note that you will need to use "%%x" instead of "%x" if you
place this statement in a batch file.

The .OBJ files created by this process will be compatible with
QuickBasic strings and PDS near strings.  If you have PDS and
would like to create a far string version of PBClone, you must
set the FarString label when assembling.  Far strings are also
required for the VB-DOS compiler.

   FOR %x IN (*.ASM) DO MASM %x /DFarString ;

You can most readily create a library from the resulting .OBJ
files by using the LibMatic or LibWiz utilities.  Due to the
size of PBClone, manual library creation is not recommended.

If you find any bugs or problems with PBClone, or have any
suggestions to make, please let me know.  You can reach me
through any of the BBSes listed in WHERE.BBS, or write to me by
conventional mail.  Please DO NOT call me directly!  I loathe a
ringing phone.  Phones were meant for modem use only!

                      Routine Reference



Array Management:
   AddMatI       add to each element of an integer array
   AddMatL       add to each element of a long integer array
   BinSeekD      search a sorted array of double-precision nos.
   BinSeekI      search a sorted array of integers
   BinSeekL      search a sorted array of long integers
   BinSeekS      search a sorted array of single-precision nos.
   BinSeekSt     search a sorted array of strings
   DRecDel       delete a record or element from an array
   DRecIns       insert a record or element into an array
   InitPtr       initialize an array of pointers
   MeanAverageD  calculate the average of a double-prec. array
   MeanAverageI  calculate the average of an integer array
   MeanAverageL  calculate the average of a long integer array
   MeanAverageS  calculate the average of a single-prec. array
   MulMatI       multiply each element of an integer array
   PSortD        pointer-sort a double-prec. array
   PSortI        pointer-sort an integer array
   PSortL        pointer-sort a long integer array
   PSortS        pointer-sort a single-prec. array
   PSortSt       pointer-sort a string array
   ReverseD      reverse the elements in a double-prec. array
   ReverseI      reverse the elements in an integer array
   ReverseL      reverse the elements in a long integer array
   ReverseS      reverse the elements in a single-prec. array
   ReverseSt     reverse the elements in a string array
   SetMatI       set each element of an integer array
   SetMatL       set each element of a long integer array
   SortD         sort an array of double-precision numbers
   SortI         sort an array of integers
   SortL         sort an array of long integers
   SortS         sort an array of single-precision numbers
   SortSt        sort an array of strings

                      Routine Reference



Disk:
   BootDrive$    determine the drive used to boot the computer
   CDROM         see if a CD-ROM is installed and get info
   CheckDisk     see if a disk is ready to be accessed
   CheckDsk%     see if a disk is ready to be accessed
   CheckShare    determine whether SHARE is installed
   CheckShare2%  determine whether SHARE is installed
   DelSub        delete a subdirectory
   DiskStat      get information on disk memory
   DReadAbs      read absolute disk sector (drive <32M)
   DReadAbsBig   read absolute disk sector (any size drive)
   DriveSpace&   see how much space is free on a disk
   DrvType       see if a drive is removeable and/or networked
   DWriteAbs     write absolute disk sector (drive <32M)
   DWriteAbsBig  write absolute disk sector (any size drive)
   FDescRead$    read a 4DOS-style file description
   FindFirstF    find the first file to match specs
   FindFirstFx   find the first file to match specs
   FindNextF     find any other files which match specs
   FindNextFx    find any other files which match specs
   Floppies      see how many floppy drives are attached
   Floppies2%    see how many floppy drives are attached
   FloppyType    see what types of floppy drives are installed
   FReadLn       read a line of text from a file (LINE INPUT#)
   GetAttrF      get attribute of a file matched by FindFirstF
   GetAttrFx%    get attribute of a file matched by FindFirstFx
   GetDateF      get date of a file matched by FindFirstF
   GetDateFx$    get date of a file matched by FindFirstFx
   GetDrive$     get the default drive
   GetExecPath   get drive, subdir, name of current program
   GetLabel      get a disk volume label
   GetNameF      get the name of a file matched by FindFirstF
   GetNameFx$    get the name of a file matched by FindFirstFx
   GetSerial     get a disk serial number
   GetSizeFL     get the size of a file matched by FindFirstF
   GetSizeFx&    get the size of a file matched by FindFirstFx
   GetSub        get the default subdirectory
   GetSub1       get the default subdirectory on a given drive
   GetTimeF      get the time of a file matched by FindFirstF
   GetTimeFx$    get the time of a file matched by FindFirstFx
   GetVerify     determine status of the DOS "verify" setting
   LoadDir       load names of matching files into an array
   LoadDirAll    load all info about matching files into array
   LogicalDrives% see how many logical drives are available
   MakeSub       create a subdirectory
   RenSub        rename a subdirectory
   Retries       set the retries used for file networking
   SetDrv        set the default drive
   SetLabel      set a disk volume label
   SetLogiDrive  set logical drive (useful for 1-floppy setups)
   SetSub        set the default subdirectory
   SetVerify     set the state of the DOS "verify" switch
   SubExist      determine whether a subdirectory exists
   SubExist2%    determine whether a subdirectory exists

                      Routine Reference



Display:
   BigPrint      display text in huge letters
   BkSpace       backspace destructively with wrap
   BkScroll      scroll an area of the screen down
   Blink         switch blinking vs. intense background colors
   CalcAttr      calc color/attribute from fore & background
   CalcAttr2%    calc color/attribute from fore & background
   CalcSize      calc array size needed to save a screen area
   CalcVGAColor  calculate a VGA palette color setting
   ClearArea     clear an area of the screen w/ special effects
   Clock         display a clock on the screen constantly
   ClockSet      set various parameters for the clock
   ClrCols       clear between specified columns on a row
   ClrEOL        clear to the end of the row
   ClrEOP        clear to the end of the screen
   ClrSOL        clear to the start of the row
   ClrSOP        clear to the start of the screen
   CPrintScreen1 send a SCREEN 1 display to the printer
   CPrintScreen2 send a SCREEN 2 display to the printer
   CursorInfo    return cursor visibility, current & max sizes
   CWindowManC   display pop-up window in CGA graphics mode
   DClear        clear a display being kept in an array
   DClearSS      clear a display of unusual size in an array
   DelChr        delete a character from the screen
   DelLine       delete a row from the screen
   DGClear       clear a CGA virtual screen
   DGetScreen    get an area of the screen into an array
   DGQPrint      write to a CGA virtual screen (SCREEN 1 type)
   DGXQPrint     write to a CGA virtual screen (SCREEN 2 type)
   DGXQPrint1    write to a CGA virtual screen (SCREEN 2 type)
   Dissolve      clear the screen with special effects
   DMPrint       display text directly through DOS services
   DOSClrEol     clear from the cursor to end of line via DOS
   DOSCls        clears the screen using DOS output
   DOSColor      sets the screen color using DOS output
   DOSLocate     sets the cursor position using DOS output
   DPutScreen    put an array onto an area of the screen
   DRecolor      recolor text of a specified color in an array
   DRecolorArea  recolor a block of text in an array
   DScrRest      restore a saved screen from an array
   DScrSave      save a screen to an array or other memory
   DWindowMan    make a pop-up window in an array
   DWindowMan2   pop-up window in an array (definable frames)
   DWindowMan3   pop-up window in an array (array-based parms)
   DWindowMan4   pop-up window in an array (Spartan version)
   DXQPrint      write text into an array
   EGARest7      restore a saved screen to EGA SCREEN 7 display
   EGARest8      restore a saved screen to EGA SCREEN 8 display
   EGARest9      restore a saved screen to EGA SCREEN 9 display
   EGASave7      save an EGA SCREEN 7 display to an array
   EGASave8      save an EGA SCREEN 8 display to an array
   EGASave9      save an EGA SCREEN 9 display to an array

                      Routine Reference



Display:
   EWindowManC   display pop-up window on EGA/VGA graphics
   EXQPrintC     display text at high speed on EGA/VGA graphics
   FadeOut       clear the screen with special effects
   GetColor      get the current colors being used by BASIC
   GetCRT%       determine whether the display is color or mono
   GetEGA        see if an EGA is in use and get info about it
   GetEGA2%      see if an EGA is in use
   GetHGA%       see if a Hercules mono adapter is in use
   GetLine       get a row of text from virtual or saved screen
   GetRows%      see how many rows are on the screen
   GetScreen     get an area of the screen into an array
   GetVGA        see if a VGA is in use
   GetVGA2%      see if a VGA is in use
   GetVGAColor   get the specified VGA palette setting
   GetVGAPalette get the specified VGA palette settings
   GetVidMode    get display mode and other screen info
   GQPrint       display text quickly in CGA SCREEN 2 mode
   GrafPrint     display sized text at graphics coordinates
   GrafRest      restore a saved CGA graphics screen
   GrafSave      save a CGA graphics screen to an array
   GXQPrint      display text quickly in CGA SCREEN 1
   GXQPrint1     display text quickly in CGA SCREEN 1
   HCls          clear screen in Hercules graphics mode
   HiLite        highlight text on the screen
   HLine         draw a line in Hercules graphics mode
   HMode         switch between text and Herc graphics modes
   HPrint        display text in Hercules graphics mode
   HSetPixel     plot a point in Hercules graphics mode
   HTestPixel    get the color of a point in Herc graphics mode
   InsChr        insert a space onto the screen
   InsLine       insert a blank row onto the screen
   LScroll       scroll an area of the screen left
   MPrint        display text through DOS, obeying MWindow
   MWindow       sets a display region for MPrint
   PrintBox      display a box of characters or strings
   PrintScreen   print the screen on a printer
   PutScreen     put an array onto an area of the screen
   QPrint        display text very quickly
   ReadScreen    read a string from the screen
   ReColor       change text of a selected color to a new color
   ReColorArea   change text in a selected area to a new color
   RScroll       scroll an area of the screen right
   Scroll        scroll an area of the screen up
   ScrRest       restore a saved screen from an array
   ScrSave       save a screen to an array
   SCrunch       compress an 80x25 text screen in an array
   SCrunchSS     compress any size of text screen in an array
   SetCGAColor   set various aspects of CGA colors
   SetVGAColor   set the specified VGA palette info (1 color)
   SetVGAPalette set the specified VGA palette info (1+ colors)

                      Routine Reference



Display:
   ShowIcon      display a Windows icon file (.ICO)
   Split         clear the screen by scrolling different ways
   TypePrint     display text as if it is being typed
   UnCalcAttr    convert color/attribute to fore & background
   UnSCrunch     uncompress a "scrunched" screen (80x25 only)
   UnSCrunchSS   uncompress a "scrunched" screen (any size)
   UnSplit       restore saved screen by scroll. different ways
   VGARest13     restore a saved screen in VGA SCREEN 13 mode
   VGASave13     save a VGA SCREEN 13 display to an array
   WindowMan     display a pop-up window
   WindowMan2    display a pop-up window (user-defined frames)
   WindowMan3    display a pop-up window (array-based parms)
   WindowMan4    display a pop-up window (spartan version)
   XMPrint       display text through DOS after translation
   XQPrint       display text very quickly
   XQPrintOver   quick text display, overlaying existing text

Equipment:
   AllExtMem&    see how much extended memory was found at boot
   BootDrive     determine the drive used to boot the computer
   BootDrive2$   determine the drive used to boot the computer
   CDROM         see if a CD-ROM is installed and get info
   CPUSpeed%     get the CPU speed in MHz
   Equipment     find out about basic equipment (ports, memory)
   ExtMem        see how much extended memory is available
   Floppies      see how many floppy drives are available
   Floppies2%    see how many floppy drives are available
   FloppyType    see what types of floppy drives are installed
   Get4DOSv      get installed version of 4DOS, if any
   GetCRT%       determine whether the display is color or mono
   GetDOSv       get the DOS version
   GetEGA        see if an EGA is in use and get info about it
   GetEGA2%      see if an EGA is in use
   GetExtM       see how much extended memory is available
   GetHGA%       see if a Hercules mono adapter is in use
   GetLIMm       see how much expanded memory is available
   GetLIMv       get the EMS driver version
   GetMouseVer   get mouse driver version and hardware info
   GetVGA        see if a VGA is in use
   GetVGA2%      see if a VGA is in use
   GetXMSm       see how much XMS memory is available
   GetXMSv       get the XMS driver version
   KbdType       see if the keyboard is enhanced (101-key)
   KbdType2%     see if the keyboard is enhanced (101-key)
   LogicalDrives% see how many logical drives are available
   MMCheck       see if a mouse is available and # of buttons
   MMCheck2%     see if a mouse is available and # of buttons
   NumProc       see what kind of numeric coprocessor is in use
   NumProc2%     see what kind of numeric coprocessor is in use
   PCDat$        get the date of the ROM BIOS
   PCDate        get the date of the ROM BIOS
   PCType        get the machine I.D. from the ROM BIOS
   PCType2%      get the machine I.D. from the ROM BIOS
   Processor     see what kind of CPU is in use
   Processor2%   see what kind of CPU is in use
   WinCheck      see what version of Windows is running, if any

                      Routine Reference



File:
   BRead         read a byte from a file into an integer
   BWrite        write a byte to a file from an integer
   CloseA        close an archive opened by FindFirstA
   CopyFile      copy a single file
   DelFile       delete a file
   DFRead        read from a file into an array or other mem.
   DFWrite       write to a file from an array or other memory
   Exist         see if a file exists
   Exist2%       see if a file exists
   ExplainFAttr$ return a text explanation of a file attribute
   ExtendFSpec   check, complete, and format a filespec
   FClose1       close a file
   FCreate       create a file and open it for access
   FGetLoc       get the position of a file pointer
   FGetLoc2&     get the position of a file pointer
   FileCopy      copy one or more files
   FileCount     count the number of matching files
   FileCRC       calculate a 32-bit CRC for a file
   FindFirstA    find the first file in an archive
   FindNextA     find any other files in an archive
   FindPatch     find where to patch an .EXE
   FLock         lock any part of a file
   FlushToDisk   flush a file to disk (force it to be updated)
   FOpen1        open a file
   ForceMatch$   force a filename to match a wildcard pattern
   FSetEnd       move to the end of a file
   FSetLoc       move to a specific location in a file
   FSetOfs       move backwards or forwards within a file
   FSetRec       move to a specific record location in a file
   FSetSize      set the size of a file
   FSize         get the size of a file
   FSize2&       get the size of a file
   FUnlock       unlock any part of a file (use w/ FLock)
   GetCRCA       get CRC-16 of a file matched by FindFirstA
   GetCRCAL      get CRC-32 of a file matched by FindFirstA
   GetDateA      get date of a file matched by FindFirstA
   GetFAttr      get attribute of a file
   GetFDate      get the date of a file
   GetFSize&     get the size of a file
   GetFTime      get the time of a file
   GetNameA      get the name of a file matched by FindFirstA
   GetSizeAL     get the size of a file matched by FindFirstA
   GetStoreA     get storage type of file matched by FindFirstA
   GetTimeA      get the time of a file matched by FindFirstA
   GLoad         load a binary image from a file (like BLOAD)
   IdentifyFile  try to identify a file
   IRead         read an integer from a file
   IWrite        write an integer to a file
   LIRead        read an integer from a file into a long int
   LIWrite       write an integer to a file from a long integer
   LRead         read a long integer from a file
   LWrite        write a long integer to a file

                      Routine Reference



File:
   MatchFile     see if a filename matches a wildcard filespec
   ObjScan       scan an .OBJ file, return publics & externals
   ParseFSpec    split filespec into drive, subdir, filename
   PatchDone     terminates patching of an .EXE file
   Rename        rename a file
   SetFAttr      set the attribute of a file
   SetFTD        set the time and date of a file
   SetPatch      installs a patch into an .EXE file
   SFRead        read from a file into a string
   SFWrite       write from a string into a file



Input:
   AltKey        returns letter from ASCII & scan codes of key
   BarMenu       bar menu (single row) for keyboard only
   BarMenuM      bar menu (single row) for keyboard or mouse
   BIOSInkey     get a key from BIOS if any is waiting
   BoxMenu       box menu (single column) for picking one item
   BoxMenu1      box menu (single column) for picking items
   BreakCheck    see if Break has been pressed
   BreakOff      make sure Break doesn't interrupt the program
   BreakOffDone  remove Break handler
   CheckKey      get a key if any is waiting, or a mouse button
   CheckKey3     get a key if any is waiting, or a mouse button
   ClrKbd        clear the keyboard buffer
   CtrlKey       returns letter, given ASCII code of Ctrl key
   DInput        formatted dollar input routine
   DOSInkey      get a key from DOS if any is waiting
   DOSInky$      get a key from DOS if any is waiting
   EnhKbd        enable/disable enhanced keyboard handling
   FileMenu      menu for picking a file
   GetKbd        get state of keyboard toggles (CapsLock, etc)
   GetKbd1       get state of shift keys (Control, Alt, etc)
   GetKbd2       get state of shift keys (Left/Right Alt, etc)
   GetKey        get a key or mouse click (wait; 2-button)
   GetKey3       get a key or mouse click (wait; 3-button)
   GetPrtSc%     get whether Print Screen was pressed
   GetValidKey   get one of a list of valid keys
   KbdType       see if the keyboard is enhanced (101-key)
   KbdType2%     see if the keyboard is enhanced (101-key)
   KeyPress      see if a key is waiting to be retrieved
   PrtSc         disable the PrtSc/PrintScreen key
   ScanKey       get a key, if any, w/o taking it from buffer
   SetKbd        set state of keyboard toggles (CapsLock, etc)
   SetMouseLoc   set the mouse cursor position (text mode)
   SInput        flexible replacement for LINE INPUT
   SInputSet     set SInput parms (fill, exitmode, beeps, fast)
   SInputSet1    set SInput parms (cursor position, full exit)
   SInputSet2    set SInput parms (capitalize, tab exit)
   SpeedKey      change the keyboard repeat rate
   TypeIn        stuff keys into buffer as if they were typed

                      Routine Reference



Memory:
   BlockMove     copy data from one area of memory to another
   DataSeg       determine the default data segment (dgroup)
   DataSeg2%     determine the default data segment (dgroup)
   EMSBuffer     get the bytes needed to save EMS array state
   EMSClose      close an EMS array
   EMSGet        get an element from an EMS array
   EMSOpen       create an EMS array
   EMSPut        put an element into an EMS array
   EMSRest       restore the EMS array state
   EMSSave       save the EMS array state
   ExtGet        get data from extended memory
   ExtMem        see how much extended memory is available
   ExtPut        put data into extended memory
   FarPeek%      get byte from memory (like PEEK w/o DEF SEG)
   FarPeekI%     get word from memory (like two PEEKs)
   FarPeekL&     get dword from memory (like four PEEKs)
   FarPoke       put byte into memory (like POKE w/o DEF SEG)
   FarPokeI      put word into memory (like two POKEs)
   FarPokeL      put dword into memory (like four POKEs)
   GetExtM       see how much extended memory is available
   GetLIMHandles get the number of EMS handles being used
   GetLIMm       see how much expanded memory is available
   GetLIMv       get the EMS driver version
   GetMemBox     get location and size of MEMBOX TSR memory
   GetPSP%       get the segment of the Program Segment Prefix
   GetXMSm       see how much XMS memory is available
   GetXMSv       get the EMS driver version
   LClose        close a block of expanded memory
   LGet          get a block of data from expanded memory
   LOpen         open a block of expanded memory
   LPut          put a block of data into expanded memory
   MemSwap       swap contents of one area of memory w/ another

Miscellaneous:
   Command2$     get the original DOS command line
   DOSErrM$      convert a DOS error code into a text message
   DOSInt%       execute a DOS function (like CALL INTERRUPT)
   DupeVar       copy a TYPEd variable into a different TYPE
   CatchError    set up to grab exit code from SHELLed program
   GetError      get the exit code from a SHELLed program
   GetError2%    get the exit code from a SHELLed program
   GetSwitch$    get the DOS switch character
   HandleInfo    see if a handle refers to a file or a device
   IntVector     get the address of an interrupt handler
   Reboot        boot the computer (like Control-Alt-Del)
   RedirectIn    see whether input has been redirected
   RedirectOut   see whether output has been redirected
   SetError      set exit code to return when program ends
   TVIdle        return clock ticks to TopView, DESQview, et al

                      Routine Reference



Mouse:
   CheckKey      get a key if any is waiting, or a mouse button
   CheckKey3     get a key if any is waiting, or a mouse button
   GetKey        get key or mouse click (wait for it; 2-button)
   GetKey3       get key or mouse click (wait for it; 3-button)
   GetMouseLoc   get the mouse cursor position (text mode)
   GetMouseVer   get mouse driver version and hardware info
   MMButton      see which mouse buttons are pressed (2-button)
   MMButton3     see which mouse buttons are pressed (3-button)
   MMCheck       see if a mouse is installed & no. of buttons
   MMCheck2%     see if a mouse is installed & no. of buttons
   MMClick       see which buttons have been pressed (2-button)
   MMClick3      see which buttons have been pressed (3-button)
   MMCursorOff   make the mouse cursor invisible
   MMCursorOn    make the mouse cursor visible
   MMGetLoc      get the mouse cursor position
   MMSetLoc      set the mouse cursor position
   MMSetRange    set the allowable range of the mouse cursor
   MouseBuffer   get no. of bytes needed to save mouse state
   MouseCursor   set the mouse graphics cursor type
   MousePen      turn light pen emulation by the mouse on/off
   MouseRest     restore a saved mouse state
   MouseSave     save the current state of the mouse
   SetMouseLoc   set the mouse cursor position (text mode)

                      Routine Reference



Numeric:
   Any2Dec       convert a number from any base into an integer
   CeilD#        return the smallest integer >= number
   CeilS!        return the smallest integer >= number
   Dec2Any       convert an integer to any base
   FloorD#       return the largest integer <= number
   FloorS#       return the largest integer <= number
   HiByte%       return the high byte of an integer
   HiWord%       return the high word of a long integer
   IVal%         convert a string to an integer
   KVal%         convert a string to a long integer / 1024
   LoByte%       return the low byte of an integer
   LoWord%       return the low word of a long integer
   LVal%         convert a string to a long integer
   Max%          return the greater of two integers
   MaxD#         return the greater of two double-prec. numbers
   MaxL&         return the greater of two long integers
   MaxS!         return the greater of two single-prec. numbers
   Min%          return the smaller of two integers
   MinD#         return the smaller of two double-prec. numbers
   MinL&         return the smaller of two long integers
   MinS!         return the smaller of two single-prec. numbers
   Num2Phone$    convert a compressed phone number to a string
   NumFormat     format a number as a string, like PRINT USING
   Odd%          return whether an integer is odd
   OddL%         return whether a long integer is odd
   Phone2Num&    compress a phone number into a long integer
   Rand%         return pseudo-random number in specified range
   ReadBitF      read value of given bit length from an array
   RotateL       rotate the bits in an integer left
   RotateLL      rotate the bits in a long integer left
   RotateR       rotate the bits in an integer right
   RotateRL      rotate the bits in a long integer right
   SetBit        set a specified bit in an integer
   ShiftL        shift the bits in an integer left
   ShiftLL       shift the bits in a long integer left
   ShiftR        shift the bits in an integer right
   ShiftRL       shift the bits in a long integer right
   WriteBitF     write value of given bit length into an array

Printer:
   CPrintScreen1 send a SCREEN 1 display to the printer
   CPrintScreen2 send a SCREEN 2 display to the printer
   GetPrtAddr    get the address of a printer port
   PrinterReady% see if a printer is ready
   PrinterInit   initialize a printer
   PrintFile     send a file to the printer
   PrintScreen   print the screen on the printer
   PrtSc         disable the PrtSc/PrintScreen key
   PrtSwap       swap any two printer ports
   SetPrtAddr    set the address of a printer port
   Spooler       see if DOS print spooler (PRINT.COM) is loaded

                      Routine Reference



Serial:
   Carrier       determine if a carrier is present
   Checksum      calculate a checksum for a string
   Checksum2%    calculate a checksum for a string
   CRC           calculate a CRC for a string (obsolete)
   CRC1          calculate a CRC for a string
   DTR           set the state of the DTR line
   GetCommAddr   get the address of a comm port
   SetComm       set communications parameters
   SetCommAddr   set the address of a comm port



String:
   AndSt         AND the bytes in two strings together
   AscI%         get the ASCII value of a character (like ASC)
   AscM%         get the ASCII value of any char in a string
   Bickel        compare two strings using Bickel's algorithm
   BSq           compress the blanks out of a text string
   BUsq          restore a string that was compressed by BSq
   BUsqLen       determine expanded length of a BSq'ed string
   CenterSt$     center a string
   Cipher        perform simple string encryption/decryption
   CipherP       like Cipher, only the results are printable
   CRC           calculate a 16-bit CRC
   Crunch        remove repeated values from a string
   DGetRec       get a string from memory in a record format
   DGetSt        get string from numeric array or other memory
   DPutRec       put a string into memory in a record format
   DPutSt        put string into numeric array or other memory
   ExtendFSpec   check, complete, and format a filespec
   Extract       extract a delimited substring from a string
   ForceMatch$   force a filename to match a wildcard pattern
   FromPostal$   convert a postal abbreviation to a state name
   IsAlNum%      test whether a char. is alphabetic or numeric
   IsAlpha%      test whether a character is alphabetic
   IsASCII%      test whether a character is ASCII
   IsCntrl%      test whether a character is a control code
   IsDigit%      test whether a character is a digit
   IsLower%      test whether a char. is lowercase alphabetic
   IsPrint%      test whether a character is printable
   IsPunct%      test whether a character is punctuation
   IsSpace%      test whether a character is white space
   IStr$         convert an integer to a string (like STR$)
   IStrNB$       convert an integer to a string w/o blank
   IsUpper%      test whether a char. is uppercase alphabetic
   IsXDigit%     test whether a char. is a hexadecimal digit
   Locase        convert a string to lowercase (U.S. only)
   Locase1       convert a string to lowercase (international)
   LRotate       rotate the characters in a string left once

                      Routine Reference



String:
   MatchFile     see if filename matches a wildcard filespec
   Month0        return the name of the month, given month no.
   MultiAND      perform an arithmetic AND operation on string
   MultiOR       perform an arithmetic OR operation on a string
   MultiXOR      perform an arithmetic XOR operation on string
   NameCase      capitalize a string correctly for a name
   NameCase2$    capitalize a string correctly for a name
   Num2Phone$    convert a compressed phone number to a string
   OrSt          OR bytes in one string with those in another
   Phone2Num&    compress a phone number into a long integer
   Replace       replace one character with another
   ReplaceSt     replace one substring with another
   Reverse       reverse a string
   RInstr        find last occurrence of substring w/in string
   RolSt         rotate the bits in a string left
   RorSt         rotate the bits in a string right
   RRotate       rotate the characters in a string right once
   SFRead        read a string from a file
   SFWrite       write a string to a file
   ShlSt         shift the bits in a string left
   ShrSt         shift the bits in a string right
   Soundex       determine what a string "sounds" like
   SSrch         see if one string is within another
   StrDel        delete a character from a string
   StrIns        insert a space into a string
   Strip         strip the blanks from both sides of a string
   Strip2$       strip the blanks from both sides of a string
   StripBlanks   strip the blanks from side(s) of a string
   StripChar     strip a specified list of chars from a string
   StripRange    strip a specified range of chars from a string
   StripSpaces   strip the spaces from side(s) of a string
   StrSqu$       compress text string using 2&3-gram compress.
   StrSqu2       compress text string using 2-gram compression
   StrSqu3       compress text string using 3-gram compression
   StrSquLen2    determine 2-gram compressed length of string
   StrSquLen3    determine 3-gram compressed length of string
   StrUnsq$      uncompress a 2 & 3-gram compressed string
   StrUnsqu2     uncompress a 2-gram compressed string
   StrUnsqu3     uncompress a 3-gram compressed string
   StrUnsquLen2  calc full length of 2-gram compressed string
   StrUnsquLen3  calc full length of 3-gram compressed string
   TInstr        search for a specific kind of char in a string
   ToPostal$     convert state name to its postal abbreviation
   Upcase        convert a string to uppercase (U.S. only)
   Upcase1       convert a string to uppercase (international)
   UpcaseI       convert an ASCII code to uppercase (U.S. only)
   UpcaseI1      convert ASCII to uppercase (international)
   Xlate         run each char of a string through translation
   XorSt         XOR bytes in one string with those in another

                      Routine Reference



Time:
   CalcDate      get date a number of days from a starting date
   CheckDate     check a date to determine whether it is valid
   Clock         display a clock on the screen, constantly
   ClockSet      set the parameters for the clock
   Date2Int      squash a date into a single integer
   DateA2R       convert a date to a number you can calc with
   DateN2S       convert a date from numbers into a string
   DateR2A       convert a number to a date
   DateS2N       convert a date from string form into numbers
   DCal          draw a calendar into an array for ScrRest
   DCalendar     draw a calendar & let user to select date
   Delay         delay for a given number of seconds
   Delay18th     delay for a given number of 18ths of seconds
   DelayV        delay for a very small amount of time
   Elapsed       determine the elapsed time between two times
   ElapsedTime$  determine the elapsed time between two times
   EuropeDate    convert a date to European format
   FormatDate    convert a date to any desired format
   GetDateA      get the date of a file matched by FindFirstA
   GetDateAT     get the date from the AT hardware clock
   GetDateF      get date of a file matched with FindFirstF
   GetDateFx$    get date of a file matched with FindFirstFx
   GetFDate      get the date of a file
   GetFTime      get the time of a file
   GetTick&      get timer tick count (1/18th seconds)
   GetTime       get time from DOS, including 100th seconds
   GetTimeA      get the time of a file matched by FindFirstA
   GetTimeAT     get the time from the AT hardware clock
   GetTimeF      get time of a file matched with FindFirstF
   GetTimeFx$    get time of a file matched with FindFirstFx
   Int2Date      unsquash date from single integer to numbers
   Int2DateSt$   unsquash date from single integer to string
   Int2Time      unsquash time from single integer to numbers
   Int2TimeSt$   unsquash time from single integer to string
   Month0        return name of month, given the month number
   Sec2Time$     convert seconds past midnight to time string
   SetDateAT     set the date of the AT hardware clock
   SetTimeAT     set the time of the AT hardware clock
   Time2Int      squash a time into a single integer
   Time2Sec&     convert time string to seconds past midnight
   TimeN2S       convert a time from numbers into a string
   TimeS2N       convert a time from a string into numbers
   WeekDay0      get the day of the week
   WeekDay1      returns the day of the week for a given date

                      Enhanced Key Codes



This is a list of the new key codes available when you use
EnhKbd to enable enhanced keyboard support.  Note that the
codes are direct from the BIOS, and may not always match what
INKEY$ returns.  QuickBasic 4.5 provides only minimal support
for the enhanced keys; QBX does much better.  As long as you
use PBClone for input, of course, you don't have to worry about
it.

The format used is ScanCode, ASCIIcode.


Middle keypad key (num lock off):   0,76
Middle key, with Control:           0,143

             plain     shift     control     alt
             -----     -----     -------    -----
   F11       0,133     0,135      0,137     0,139
   F12       0,134     0,136      0,138     0,140

The middle cursor pad returns the same scan codes as the
cursor/numeric pad when NumLock is off, but with an ASCII code
of 224 instead of 0.  If you want the middle cursor pad and
cursor/numeric pad to return the same values, you should have
your code do this:

   ' ...get key code...
   IF ASCIIcode = 224 AND ScanCode <> 0 THEN ASCIIcode = 0

Why test both ASCII and scan codes?  Because it is possible for
the user to enter a plain 224 by holding ALT and using the
numeric keypad, which could cause confusion.

The arrows in the middle cursor pad will return special codes
if pressed in combination with an ALT key:

   up    arrow     0,152
   down  arrow     0,160
   left  arrow     0,155
   right arrow     0,157

Finally, the arrow keys on either cursor pad will return
special codes if pressed in combination with a CONTROL key:

                   middle pad     cursor/num pad
                   ----------     --------------
   up    arrow       224,141          0,141
   down  arrow       224,145          0,145
   left  arrow       224,115          0,115
   right arrow       224,116          0,116

                        DOS Error Codes



Note that the number of error codes available depends on the
version of DOS in use.  Older versions return fewer error
codes, meaning that the nature of the error may not be
specified as precisely as you might like.  This is not a
complete list of all possible codes, but it covers the most
common ones.

The DOSErrM$ function can be used to generate a complete error
list if needed, current at least through DOS 3.31.  If later
versions of DOS have new error codes, I'm not aware of 'em.


  -1    Unable to read or write all of the data requested
   0    No error
   1    Invalid function number
   2    File not found
   3    Path not found
   4    No handle available (too many files open)
   5    Access denied (file already in use or "read only")
   6    Invalid handle
  15    Invalid disk drive
  16    Attempt to remove current directory
  18    No more matching files
  19    Disk is write-protected
  20    Unknown unit
  21    Drive not ready
  22    Invalid command
  23    Data CRC error
  25    Seek error
  26    Disk is not in DOS format
  27    Sector not found
  28    Printer is out of paper
  29    Write fault
  30    Read fault
  31    General failure
  32    Sharing violation
  33    Lock violation
  34    Invalid disk change
  35    No FCB available
  36    No room in file sharing buffer
  80    File already exists
  82    Unable to create subdirectory